---

QuickTime 4 Reference

| Previous | Chapter Contents | Chapter Top | Next |

DecompressSequenceBeginS

Sends a sample image to a decompressor.

pascal OSErr DecompressSequenceBeginS (
                     ImageSequence *seqID,
                     ImageDescriptionHandle desc,
                     Ptr data,
                     long dataSize,
                     CGrafPtr port,
                     GDHandle gdh,
                     const Rect *srcRect,
                     MatrixRecordPtr matrix,
                     short mode,
                     RgnHandle mask,
                     CodecFlags flags,
                     CodecQ accuracy,
                     DecompressorComponent codec);


seqID

Contains a pointer to a field to receive the unique identifier for this sequence returned by the CompressSequenceBegin function.

desc

Contains a handle to the image description structure that describes the compressed image.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress function before you use that pointer with this parameter.

dataSize

Specifies the size of the data buffer.

port

Points to the graphics port for the destination image.

gdh

Contains a handle to the graphics device record for the destination image.

srcRect

Contains a pointer to a rectangle defining the portions of the image to decompress.

matrix

Points to a matrix structure that specifies how to transform the image during decompression.

mode

Specifies the transfer mode for the operation.

mask

Contains a handle to the clipping region in the destination coordinate system.

flags

Contains flags providing further control information.

accuracy

Specifies the accuracy desired in the decompressed image.

codec

Contains the compressor identifier.

SetSequenceProgressProc

Installs a progress procedure for a sequence.

pascal OSErr SetSequenceProgressProc (
                     ImageSequence seqID,
                     ICMProgressProcRecord *progressProc);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

progressProc

Points to a record containing information about the application's progress procedure.

GetCSequenceMaxCompressionSize

The GetCSequenceMaxCompressionSize function allows your application to determine the maximum size an image will be after compression for a given compression sequence. You must have already started a compression sequence with CompressSequenceBegin .

pascal OSErr GetCSequenceMaxCompressionSize(
                     ImageSequence seqID,
                     PixMapHandle src,
                     long *size);


seqID

Contains the unique sequence identifier that was returned by the CompressSequenceBegin function.

src

Contains a handle to the source pixel map. The compressor uses only the image's size and pixel depth to determine the maximum size of the compressed image.

size

Contains a pointer to a field to receive the maximum size, in bytes, of the compressed image.

DecompressSequenceFrameWhen

Queues a frame for decompression and specifies the time at which decompression will begin.

pascal OSErr DecompressSequenceFrameWhen (
                     ImageSequence seqID,
                     Ptr data,
                     long dataSize,
                     CodecFlags inFlags,
                     CodecFlags *outFlags,
                     ICMCompletionProcRecordPtr asyncCompletionProc,
                     const ICMFrameTimeRecord *frameTime);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress function before you use that pointer with this parameter.

dataSize

Specifies the size of the data buffer.

inFlags

Contains flags providing further control information. See Inside Macintosh: QuickTime for information about CodecFlags fields. The following flags are valid for this function:

codecFlagNoScreenUpdate

Controls whether the decompressor updates the screen image. If you set this flag to 1, the decompressor does not write the current frame to the screen, but does write the frame to its offscreen image buffer (if one was allocated). If you set this flag to 0, the decompressor writes the frame to the screen.

codecFlagDontOffscreen

Controls whether the decompressor uses the offscreen buffer during sequence decompression. This flag is only used with sequences that have been temporally compressed. If this flag is set to 1, the decompressor does not use the offscreen buffer during decompression. Instead, the decompressor returns an error. This allows your application to refill the offscreen buffer. If this flag is set to 0, the decompressor uses the offscreen buffer if appropriate.

codecFlagOnlyScreenUpdate

Controls whether the decompressor decompresses the current frame. If you set this flag to 1, the decompressor writes the contents of its offscreen image buffer to the screen, but does not decompress the current frame. If you set this flag to 0, the decompressor decompresses the current frame and writes it to the screen. You can set this flag to 1 only if you have allocated an offscreen image buffer for use by the decompressor.

outFlags

Contains status flags. The decompressor updates these flags at the end of the decompression operation. See Inside Macintosh: QuickTime for information about CodecFlags constants. The following flags may be set by this function:

codecFlagUsedNewImageBuffer

Indicates to your application that the decompressor used the offscreen image buffer for the first time when it processed this frame. If this flag is set to 1, the decompressor used the image buffer for this frame and this is the first time the decompressor used the image buffer in this sequence.

codecFlagUsedImageBuffer

Indicates whether the decompressor used the offscreen image buffer. If the decompressor used the image buffer during the decompress operation, it sets this flag to 1. Otherwise, it sets this flag to 0.

codecFlagDontUseNewImageBuffer

This input flag forces an error to be returned when a new image buffer would have to be allocated instead of allocating the new buffer.

codecFlagInterlaceUpdate

This input flag updates the screen interlacing even and odd scan lines to reduce tearing artifacts (if the decompressor supports this mode).

codecFlagCatchUpDiff

This input flag notifies the codec that the currently displayed frame is being displayed late in an attempt to "catch up" to the current frame, which only happens with compression formats that support frame differencing.

asyncCompletionProc

Points to a completion function structure. The compressor calls your completion function when an asynchronous decompression operation is complete. You can cause the decompression to be performed asynchronously by specifying a completion function. See Inside Macintosh: QuickTime for more information about completion functions.

If you specify asynchronous operation, you must not read the decompressed image until the decompressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to nil to specify synchronous decompression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the decompressor does not call your completion function.

frameTime

Points to a structure that contains the frame's time information, including the time at which the frame should be displayed, its duration, and the movie's playback rate. This parameter can be nil, in which case the decompression operation will happen immediately.

DecompressSequenceFrameS

Queues a frame for decompression and specifies the size of the compressed data. New applications should use DecompressSequenceFrameWhen .

pascal OSErr DecompressSequenceFrameS(
                     ImageSequence seqID,
                     Ptr data,
                     long dataSize,
                     CodecFlags inFlags,
                     CodecFlags *outFlags,
                     ICMCompletionProcRecordPtr asyncCompletionProc);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

data

Points to the compressed image data. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress function before you use that pointer with this parameter.

dataSize

Specifies the size of the data buffer.

inFlags

Contains flags providing further control information. See Inside Macintosh: QuickTime for information about CodecFlags fields. The following flags are valid for this function:

codecFlagNoScreenUpdate

Controls whether the decompressor updates the screen image. If you set this flag to 1, the decompressor does not write the current frame to the screen, but does write the frame to its offscreen image buffer (if one was allocated). If you set this flag to 0, the decompressor writes the frame to the screen.

codecFlagDontOffscreen

Controls whether the decompressor uses the offscreen buffer during sequence decompression. This flag is only used with sequences that have been temporally compressed. If this flag is set to 1, the decompressor does not use the offscreen buffer during decompression. Instead, the decompressor returns an error. This allows your application to refill the offscreen buffer. If this flag is set to 0, the decompressor uses the offscreen buffer if appropriate.

codecFlagOnlyScreenUpdate

Controls whether the decompressor decompresses the current frame. If you set this flag to 1, the decompressor writes the contents of its offscreen image buffer to the screen, but does not decompress the current frame. If you set this flag to 0, the decompressor decompresses the current frame and writes it to the screen. You can set this flag to 1 only if you have allocated an offscreen image buffer for use by the decompressor.

outFlags

Contains status flags. The decompressor updates these flags at the end of the decompression operation. See Inside Macintosh: QuickTime for information about CodecFlags constants. The following flags may be set by this function:

codecFlagUsedNewImageBuffer

Indicates to your application that the decompressor used the offscreen image buffer for the first time when it processed this frame. If this flag is set to 1, the decompressor used the image buffer for this frame and this is the first time the decompressor used the image buffer in this sequence.

codecFlagUsedImageBuffer

Indicates whether the decompressor used the offscreen image buffer. If the decompressor used the image buffer during the decompress operation, it sets this flag to 1. Otherwise, it sets this flag to 0.

codecFlagDontUseNewImageBuffer

This input flag forces an error to be returned when a new image buffer would have to be allocated instead of allocating the new buffer.

codecFlagInterlaceUpdate

This input flag updates the screen interlacing even and odd scan lines to reduce tearing artifacts (if the decompressor supports this mode).

codecFlagCatchUpDiff

This input flag notifies the codec that the currently displayed frame is being displayed late in an attempt to "catch up" to the current frame, which only happens with compression formats that support frame differencing.

asyncCompletionProc

Points to a completion function structure. The compressor calls your completion function when an asynchronous decompression operation is complete. You can cause the decompression to be performed asynchronously by specifying a completion function. See Inside Macintosh: QuickTime for more information about completion functions.

If you specify asynchronous operation, you must not read the decompressed image until the decompressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to nil to specify synchronous decompression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the decompressor does not call your completion function.

CDSequenceFlush

Stops a decompression sequence, aborting processing of any queued frames.

pascal OSErr CDSequenceFlush(ImageSequence seqID);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

SetDSequenceTimeCode

Sets the timecode value for the frame that is about to be decompressed.

pascal OSErr SetDSequenceTimeCode (
                     ImageSequence seqID,
                     void TimeCodeDef *timeCodeFormat,
                     void TimeCodeTime *timeCodeTime);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

timeCodeFormat

Contains a pointer to a timecode definition structure. You provide the appropriate timecode definition information for the next frame to be decompressed.

timeCodeTime

Contains a pointer to a timecode record structure. You provide the appropriate time value for the next frame in the current sequence.

CDSequenceEquivalentImageDescription

Reports whether two image descriptions are the same.

pascal OSErr CDSequenceEquivalentImageDescription (
                     ImageSequence seqID,
                     ImageDescriptionHandle newDesc,
                     Boolean *equivalent);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

newDesc

Contains a handle to the image description structure that describes the compressed image.

equivalent

Contains a pointer to a Boolean value. If the ImageDescriptionHandle provided in the newDesc parameter is equivalent to the image description currently in use by the image sequence, this value is set to true . If the ImageDescriptionHandle is not equivilent, and therefore a new image sequence must be created to display an image using the new image description, this value is set to false .

CDSequenceNewMemory

Requests codec-allocated memory.

pascal OSErr CDSequenceNewMemory (
                     ImageSequence seqID,
                     Ptr *data,
                     Size dataSize,
                     long dataUse,
                     ICMMemoryDisposedUPP memoryGoneProc,
                     void *refCon);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

data

Returns a pointer to the allocated memory.

dataSize

Specifies the requested size of the data buffer.

dataUse

A code that indicates how the memory is to be used. For example, the memory may be used to store compressed image or mask plane data, or used as an offscreen image buffer.

If there is no benefit to storing a particular kind of data in codec memory, the codec should deny the request for the memory allocation. The defined values are for data use are:

0x0001

Memory will be used for holding compressed image data.

0x0002

Memory will be used for an offscreen image buffer.

memoryGoneProc

A pointer to a function that will be called before disposing of the memory allocated by a codec. Your callback function must be in the following form:

pascal void (*ICMMemoryDisposedProcPtr)

(Ptr memoryBlock, void *refcon);

refCon

Contains a reference constant value to be passed to your memoryGoneProc function.

CDSequenceDisposeMemory

Disposes of memory allocated by the codec.

pascal OSErr CDSequenceDisposeMemory (
                     ImageSequence seqID,
                     Ptr data);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

data

Points to the previously allocated memory block.

CDSequenceInvalidate

Notifies the Image Compression Manager that the destination port for the given image decompression sequence has been invalidated.

pascal OSErr CDSequenceInvalidate(
                     ImageSequence seqID,
                     RgnHandle invalRgn);


seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function.

rgn

A handle of the region specifiying the invalid portion of the image.